---
target: Umo Office Convert
keywords: Umo Office Convert,office在线预览,wps在线预览,docx在线预览,word在线预览,pdf在线预览
description: 将 Office、WPS 等 40 余种办公文档转换为可在线查看的文档格式，可与 Umo Office Viewer 结合使用实现办公文档的在线预览。
---

# API 接口文档

## 概述

本文描述 Umo Office Convert 服务提供的 API 接口。该服务主要用于将各种 Office 文档和 PDF 文档-转换为 [Umo Office Viewer](https://dev.umodoc.com/cn/docs/office-viewer) 可查看的格式。

## 基础信息

- 基础URL: `http://localhost:1236`（默认端口，可在环境变量中配置）
- 在非生产环境下，可以通过 `/openapi` 路径访问 Swagger UI 接口文档

## 接口列表

### 1. 检查服务状态

检查服务是否正常运行。

- **URL**: `/`
- **方法**: `GET`
- **描述**: 返回服务是否正在运行的信息，如果无法访问该路由，则代表服务未启动或服务异常。

**响应示例**:

```json
{
  "code": 200,
  "success": true,
  "data": "Umo Office Convert 服务已启动"
}
```

### 2. 上传文件进行转换

通过表单上传文件进行转换。

- **URL**: `/convert/upload`
- **方法**: `POST`
- **Content-Type**: `multipart/form-data`
- **参数**:
  - `file`: 要转换的文件（必填）

**响应**:
- 成功时返回转换后的文件流
- 失败时返回 JSON 格式的错误信息

**响应头**:
- `X-Task-Id`: 转换任务 ID
- `X-Document-Name`: 原始文档名称
- `X-From-Cache`: 是否从缓存中获取的文件
- `Content-Disposition`: 文件下载信息
- `Content-Type`: 文件类型
- `Content-Length`: 文件大小

**错误响应示例**:

```json
{
  "code": 500,
  "success": false,
  "message": "文档转换，错误原因: 转换过程中发生了异常"
}
```

### 3. 通过 JSON 数据进行转换

通过 JSON 数据提交文件信息进行转换。

- **URL**: `/convert`
- **方法**: `POST`
- **Content-Type**: `application/json`
- **请求体**:
  ```json
  {
    "path": "/path/to/测试文档.docx",
    "filename": "测试文档.docx"
  }
  ```

**响应**:
- 成功时返回转换后的文件流
- 失败时返回 JSON 格式的错误信息

### 4. 通过 URL 进行转换

通过 URL 参数提交文件信息进行转换。

- **URL**: `/convert`
- **方法**: `GET`
- **参数**:
  - `url`: 要转换的文件网络地址（必填，需 URL 编码）
  - `filename`: 原始文档的文件名称（必填，需 URL 编码）

**响应**:
- 成功时返回转换后的文件流
- 失败时返回 JSON 格式的错误信息

### 5. 根据任务 ID 获取文件

根据转换任务 ID 获取转换后的文件或原始文件。

- **URL**: `/convert/{taskId}`
- **方法**: `GET`
- **参数**:
  - `taskId`: 转换任务 ID（路径参数）
  - `target`: 获取的文件类型，可选值为 `converted`（转换后的文件）或 `original`（原始文件），默认为 `converted`

**响应**:
- 成功时返回请求的文件流
- 失败时返回 JSON 格式的错误信息

## 支持的文件格式

服务支持转换多种 Office 文档格式，所支持的格式见：[支持转换的文件格式](./office-convert#支持转换的文件格式)。

## 错误处理

所有接口在发生错误时都会返回统一格式的 JSON 响应：

```json
{
  "code": 状态码,
  "success": false,
  "message": "错误信息"
}
```

常见错误状态码：
- `400`: 请求参数错误
- `403`: 访问被拒绝（白名单限制）
- `404`: 资源不存在
- `500`: 服务器内部错误

## Webhook 通知

服务支持通过 Webhook 接收文件转换完成的通知。可以在环境变量中配置 `WEBHOOK_URL`，详见：[环境变量-Webhook 配置](./env#webhook-配置)。
